# European User Consent

Under the Google [EU User Consent Policy](https://www.google.com/about/company/consentstaging.html), you must make
certain disclosures to your users in the European Economic Area (EEA) and obtain their consent to use cookies or
other local storage, where legally required, and to use personal data (such as `AdID`) to serve ads. This policy
reflects the requirements of the `EU ePrivacy Directive` and the `General Data Protection Regulation` (GDPR).

The React Native Google Mobile Ads module provides out of the box support for helping to manage your users consent
within your application. The `AdsConsent` helper which comes with the module wraps the Google UMP SDK for both
Android & iOS, and provides a single JavaScript interface for both platforms.

## Understanding AdMob Ads

Ads served by Google can be categorized as personalized, non-personalized, Limited ads and technical ads. To understand more about what ads can be served based on a
user's consent choices, see Ad serving modes ([Android](https://developers.google.com/admob/android/privacy/ad-serving-modes) / [iOS](https://developers.google.com/admob/ios/privacy/ad-serving-modes)). 

<Info>
The `AdsConsent` helper only provides you with the tools for requesting consent, it is up to the developer to ensure the consent status is reflected throughout the app.
</Info>

## Handling consent

To setup and configure ads consent collection, start by enabling and configuring GDPR and IDFA messaging in the [Privacy & messaging section of AdMob's Web Console](https://apps.admob.com/v2/privacymessaging).

<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
<TabItem value="bare">

For Android, add the following rule into `android/app/proguard-rules.pro`:

```
-keep class com.google.android.gms.internal.consent_sdk.** { *; }
```

</TabItem>
<TabItem value="expo">

Add the `extraProguardRules` property to `app.json`, `app.config.js`, or `app.config.ts` file as described in the [Expo documentation](https://docs.expo.dev/versions/latest/sdk/build-properties/#pluginconfigtypeandroid):

```json
// <project-root>/app.json
{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "extraProguardRules": "-keep class com.google.android.gms.internal.consent_sdk.** { *; }"
          }
        }
      ]
    ]
  }
}
```

You'll need to generate a new development build before using it.

</TabItem>
</Tabs>

### Delaying app measurement

By default, the Google Mobile Ads SDK initializes app measurement and begins sending user-level event data to Google immediately when the app starts.
If your app will be used by users within the EEA, it is important you prevent app measurement until your first ad has been requested (after consent).

<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
<TabItem value="bare">

Within your projects `app.json` file, set the `delay_app_measurement_init` to `true` to delay app measurement:

```json
// <project-root>/app.json
{
  "react-native-google-mobile-ads": {
    "android_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
    "ios_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
    "delay_app_measurement_init": true
  }
}
```

</TabItem>
<TabItem value="expo">

Within your projects `app.json`, `app.config.js`, or `app.config.ts` file, set the `delayAppMeasurementInit` to `true` to delay app measurement:

```json
// <project-root>/app.json
{
  "expo": {
    "plugins": [
      [
        "react-native-google-mobile-ads",
        {
          "androidAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
          "iosAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
          "delayAppMeasurementInit": true
        }
      ]
    ]
  }
}
```

</TabItem>
</Tabs>

Once set, rebuild your application.

### App Tracking Transparency

If you configure an [ATT message](https://support.google.com/admob/answer/10115331) in your Google AdMob account, the UMP SDK will automatically handle the ATT alert.
This will also show an IDFA explainer message. If you don't want to show an explainer message you can show the ATT alert [manually](https://docs.page/invertase/react-native-google-mobile-ads#app-tracking-transparency-ios).
Also, within your projects configuration file, you have to provide a user tracking usage description (once set, rebuild your application):

<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
<TabItem value="bare">

```json
// <project-root>/app.json
{
  "react-native-google-mobile-ads": {
    "android_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
    "ios_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
    "user_tracking_usage_description": "This identifier will be used to deliver personalized ads to you."
  }
}
```

</TabItem>
<TabItem value="expo">

```json
// <project-root>/app.json
{
  "expo": {
    "plugins": [
      [
        "react-native-google-mobile-ads",
        {
          "androidAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
          "iosAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
          "userTrackingUsageDescription": "This identifier will be used to deliver personalized ads to you."
        }
      ]
    ]
  }
}
```

</TabItem>
</Tabs>

### Requesting consent information

It is recommended you request consent information each time your application starts to determine if the consent modal should be shown, e.g. due to provider changes.

The `AdsConsent` helper provides a promise based method to return the users consent status called `requestInfoUpdate`.

```js
import { AdsConsent } from 'react-native-google-mobile-ads';

const consentInfo = await AdsConsent.requestInfoUpdate();
```

The method returns an `AdsConsentInfo` interface, which provides information about consent form availability and the users consent status:

- **status**: The status can be one of 4 outcomes:
  - `UNKNOWN`: Unknown consent status.
  - `REQUIRED`: User consent required but not yet obtained.
  - `NOT_REQUIRED`: User consent not required.
  - `OBTAINED`: User consent already obtained.
- **isConsentFormAvailable**: A boolean value. If `true` a consent form is available.

**Note:** The return status of this call is the status of _form presentation and response collection_, **not
the the actual user consent**. It simply indicates if you now have a consent response to decode.
(_i.e._ if user consent is **required**, the form has been presented, and user has
**denied** the consent, the status returned by this method will be `OBTAINED`,
and not `REQUIRED` as some may expect). To check the actual consent status
see [Inspecting consent choices](/european-user-consent/#inspecting-consent-choices) below.

### Gathering user consent

You should request an update of the user's consent information at every app launch, using `requestInfoUpdate`.
This determines whether your user needs to provide consent if they haven't done so already, or if their consent has expired.

After you have received the most up-to-date consent status, call `loadAndShowConsentFormIfRequired` to load a consent form.
If the consent status is required, the SDK loads a form and immediately presents it.
The completion handler is called after the form is dismissed. If consent is not required, the completion handler is called immediately.

To make it easier we added a helper method `gatherConsent` that combines requesting consent information and loading/presenting a consent form if necessary.

Before requesting ads in your app, check if you have gathered consent aligned with your app's configured messages using `canRequestAds`.
If an error occurs during the consent gathering process, you should still attempt to request ads.
The UMP SDK uses the consent status from the previous session.

**Note:** For more information on when `canRequestAds` is `true` or `false`, see the reference documentation for [Android](https://developers.google.com/admob/android/reference/privacy/com/google/android/ump/ConsentInformation#canRequestAds()) /
[iOS](https://developers.google.com/admob/ios/privacy/api/reference/Classes/UMPConsentInformation#canrequestads).

```js
import mobileAds, { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';

const isMobileAdsStartCalledRef = useRef(false);

useEffect(() => {
  // Request consent information and load/present a consent form if necessary.
  AdsConsent.gatherConsent()
    .then(startGoogleMobileAdsSDK)
    .catch((error) => console.error('Consent gathering failed:', error));

  // This sample attempts to load ads using consent obtained in the previous session.
  // We intentionally use .then() chaining (instead of await) to ensure parallel execution.
  startGoogleMobileAdsSDK();
}, []);

async function startGoogleMobileAdsSDK() {
  const {canRequestAds} = await AdsConsent.getConsentInfo();
  if (!canRequestAds || isMobileAdsStartCalledRef.current) {
    return;
  }

  isMobileAdsStartCalledRef.current = true;

  // (Optional, iOS) Handle Apple's App Tracking Transparency manually.
  const gdprApplies = await AdsConsent.getGdprApplies();
  const hasConsentForPurposeOne = gdprApplies && (await AdsConsent.getPurposeConsents()).startsWith("1");
  if (!gdprApplies || hasConsentForPurposeOne) {
    // Request ATT...
  }

  // Initialize the Google Mobile Ads SDK.
  await mobileAds().initialize()

  // Request an ad...
}
```

> Do not persist the status. You could however store this locally in application state (e.g. React Context) and update the status on every app launch as it may change.

### Inspecting consent choices

The AdsConsentStatus tells you if you should show the modal to a user or not. Often times you want to run logic based on the user's choices. This library exports a
method that returns some of the most relevant consent flags to handle common use cases.

```js
import { AdsConsent } from 'react-native-google-mobile-ads';

const {
  activelyScanDeviceCharacteristicsForIdentification,
  applyMarketResearchToGenerateAudienceInsights,
  createAPersonalisedAdsProfile,
  createAPersonalisedContentProfile,
  developAndImproveProducts,
  measureAdPerformance,
  measureContentPerformance,
  selectBasicAds,
  selectPersonalisedAds,
  selectPersonalisedContent,
  storeAndAccessInformationOnDevice,
  usePreciseGeolocationData,
} = await AdsConsent.getUserChoices();

if (storeAndAccessInformationOnDevice === false) {
  // The user declined consent for purpose 1.
}
```

**Note:** Don't try to use this functionality to enforce user consent on iOS,
this will likely result in failed app review upon submission to Apple Store, based on [review guideline 3.2.2.vi](https://developer.apple.com/app-store/review/guidelines/#3.2.2):

> ...Apps should not require users to rate the app, review the app, watch videos, download other apps, tap on advertisements, enable tracking...

### Testing

When developing the consent flow, the behavior of the `AdsConsent` responses may not be reliable due to the environment
(e.g. using an emulator vs real device). It is possible to set a debug location to test the various responses from the
UMP SDK.

If using a real device, ensure you add it to the list of allowed devices by passing the device ID, which can be obtained from native logs or using a library
such as [react-native-device-info](https://github.com/react-native-community/react-native-device-info), to `testDeviceIdentifiers`.

> Emulators are automatically whitelisted.

To set a debug location, use the `debugGeography` key. It accepts 3 values:

- **DISABLED**: Removes any previous debug locations.
- **EEA**: Set the test device to be within the EEA.
- **NOT_EEA**: Set the test device to be outside of the EEA.

For example:

```js
import { AdsConsent, AdsConsentDebugGeography } from 'react-native-google-mobile-ads';

const consentInfo = await AdsConsent.requestInfoUpdate({
  debugGeography: AdsConsentDebugGeography.EEA,
  testDeviceIdentifiers: ['TEST-DEVICE-HASHED-ID'],
});
```

It is possible to reset the UMP state for test devices. To reset the ATT state you have to delete and reinstall your app though.

```js
import { AdsConsent } from 'react-native-google-mobile-ads';

AdsConsent.reset();
```

### Troubleshooting

In case of troubles, double-check the following artifacts:
* Original documentation for underlying UMP SDK for [Android](https://developers.google.com/admob/ump/android/quick-start) /
[iOS](https://developers.google.com/admob/ump/ios/quick-start).
* Google Help Center [European regulations](https://support.google.com/admob/topic/10115026) articles.
